home *** CD-ROM | disk | FTP | other *** search
/ PC World 2006 July & August / PCWorld_2006-07-08_cd.bin / komunikace / apache / apache_2[1].2.2-win32-x86-no_ssl.msi / Data1.cab / _678EA22D1738D69F39BDD972292414F3 < prev    next >
Text File  |  2005-02-04  |  34KB  |  807 lines
  1. /* Copyright 2000-2005 The Apache Software Foundation or its licensors, as
  2.  * applicable.
  3.  *
  4.  * Licensed under the Apache License, Version 2.0 (the "License");
  5.  * you may not use this file except in compliance with the License.
  6.  * You may obtain a copy of the License at
  7.  *
  8.  *     http://www.apache.org/licenses/LICENSE-2.0
  9.  *
  10.  * Unless required by applicable law or agreed to in writing, software
  11.  * distributed under the License is distributed on an "AS IS" BASIS,
  12.  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13.  * See the License for the specific language governing permissions and
  14.  * limitations under the License.
  15.  */
  16.  
  17. #ifndef APR_FILE_IO_H
  18. #define APR_FILE_IO_H
  19.  
  20. /**
  21.  * @file apr_file_io.h
  22.  * @brief APR File I/O Handling
  23.  */
  24.  
  25. #include "apr.h"
  26. #include "apr_pools.h"
  27. #include "apr_time.h"
  28. #include "apr_errno.h"
  29. #include "apr_file_info.h"
  30. #include "apr_inherit.h"
  31.  
  32. #define APR_WANT_STDIO          /**< for SEEK_* */
  33. #define APR_WANT_IOVEC          /**< for apr_file_writev */
  34. #include "apr_want.h"
  35.  
  36. #ifdef __cplusplus
  37. extern "C" {
  38. #endif /* __cplusplus */
  39.  
  40. /**
  41.  * @defgroup apr_file_io File I/O Handling Functions
  42.  * @ingroup APR 
  43.  * @{
  44.  */
  45.  
  46. /**
  47.  * @defgroup apr_file_open_flags File Open Flags/Routines
  48.  * @{
  49.  */
  50.  
  51. /* Note to implementors: Values in the range 0x00100000--0x80000000
  52.    are reserved for platform-specific values. */
  53.  
  54. #define APR_FOPEN_READ       0x00001  /**< Open the file for reading */
  55. #define APR_FOPEN_WRITE      0x00002  /**< Open the file for writing */
  56. #define APR_FOPEN_CREATE     0x00004  /**< Create the file if not there */
  57. #define APR_FOPEN_APPEND     0x00008  /**< Append to the end of the file */
  58. #define APR_FOPEN_TRUNCATE   0x00010  /**< Open the file and truncate
  59.                                          to 0 length */
  60. #define APR_FOPEN_BINARY     0x00020  /**< Open the file in binary mode */
  61. #define APR_FOPEN_EXCL       0x00040  /**< Open should fail if APR_CREATE
  62.                                          and file exists. */
  63. #define APR_FOPEN_BUFFERED   0x00080  /**< Open the file for buffered I/O */
  64. #define APR_FOPEN_DELONCLOSE 0x00100  /**< Delete the file after close */
  65. #define APR_FOPEN_XTHREAD    0x00200  /**< Platform dependent tag to open
  66.                                          the file for use across multiple
  67.                                          threads */
  68. #define APR_FOPEN_SHARELOCK  0x00400  /**< Platform dependent support for
  69.                                          higher level locked read/write
  70.                                          access to support writes across
  71.                                          process/machines */
  72. #define APR_FOPEN_NOCLEANUP  0x00800  /**< Do not register a cleanup
  73.                                          when the file is opened */
  74. #define APR_FOPEN_SENDFILE_ENABLED 0x01000 /**< Advisory flag that this
  75.                                              file should support
  76.                                              apr_socket_sendfile operation */
  77. #define APR_FOPEN_LARGEFILE   0x04000 /**< Platform dependent flag to enable
  78.                                          large file support; WARNING see
  79.                                          below. */
  80. /* backcompat */
  81. #define APR_READ             APR_FOPEN_READ       /**< @deprecated @see APR_FOPEN_READ */
  82. #define APR_WRITE            APR_FOPEN_WRITE      /**< @deprecated @see APR_FOPEN_WRITE */   
  83. #define APR_CREATE           APR_FOPEN_CREATE     /**< @deprecated @see APR_FOPEN_CREATE */   
  84. #define APR_APPEND           APR_FOPEN_APPEND     /**< @deprecated @see APR_FOPEN_APPEND */   
  85. #define APR_TRUNCATE         APR_FOPEN_TRUNCATE   /**< @deprecated @see APR_FOPEN_TRUNCATE */   
  86. #define APR_BINARY           APR_FOPEN_BINARY     /**< @deprecated @see APR_FOPEN_BINARY */   
  87. #define APR_EXCL             APR_FOPEN_EXCL       /**< @deprecated @see APR_FOPEN_EXCL */   
  88. #define APR_BUFFERED         APR_FOPEN_BUFFERED   /**< @deprecated @see APR_FOPEN_BUFFERED */   
  89. #define APR_DELONCLOSE       APR_FOPEN_DELONCLOSE /**< @deprecated @see APR_FOPEN_DELONCLOSE */   
  90. #define APR_XTHREAD          APR_FOPEN_XTHREAD    /**< @deprecated @see APR_FOPEN_XTHREAD */   
  91. #define APR_SHARELOCK        APR_FOPEN_SHARELOCK  /**< @deprecated @see APR_FOPEN_SHARELOCK */   
  92. #define APR_FILE_NOCLEANUP   APR_FOPEN_NOCLEANUP  /**< @deprecated @see APR_FOPEN_NOCLEANUP */   
  93. #define APR_SENDFILE_ENABLED APR_FOPEN_SENDFILE_ENABLED /**< @deprecated @see APR_FOPEN_SENDFILE_ENABLED */   
  94. #define APR_LARGEFILE        APR_FOPEN_LARGEFILE  /**< @deprecated @see APR_FOPEN_LARGEFILE */   
  95.  
  96. /** @warning The APR_LARGEFILE flag only has effect on some platforms
  97.  * where sizeof(apr_off_t) == 4.  Where implemented, it allows opening
  98.  * and writing to a file which exceeds the size which can be
  99.  * represented by apr_off_t (2 gigabytes).  When a file's size does
  100.  * exceed 2Gb, apr_file_info_get() will fail with an error on the
  101.  * descriptor, likewise apr_stat()/apr_lstat() will fail on the
  102.  * filename.  apr_dir_read() will fail with APR_INCOMPLETE on a
  103.  * directory entry for a large file depending on the particular
  104.  * APR_FINFO_* flags.  Generally, it is not recommended to use this
  105.  * flag. */
  106.  
  107. /** @} */
  108.  
  109. /**
  110.  * @defgroup apr_file_seek_flags File Seek Flags
  111.  * @{
  112.  */
  113.  
  114. /* flags for apr_file_seek */
  115. /** Set the file position */
  116. #define APR_SET SEEK_SET
  117. /** Current */
  118. #define APR_CUR SEEK_CUR
  119. /** Go to end of file */
  120. #define APR_END SEEK_END
  121. /** @} */
  122.  
  123. /**
  124.  * @defgroup apr_file_attrs_set_flags File Attribute Flags
  125.  * @{
  126.  */
  127.  
  128. /* flags for apr_file_attrs_set */
  129. #define APR_FILE_ATTR_READONLY   0x01          /**< File is read-only */
  130. #define APR_FILE_ATTR_EXECUTABLE 0x02          /**< File is executable */
  131. #define APR_FILE_ATTR_HIDDEN     0x04          /**< File is hidden */
  132. /** @} */
  133.  
  134. /**
  135.  * @defgroup apr_file_writev{_full} max iovec size
  136.  * @{
  137.  */
  138. #if defined(DOXYGEN)
  139. #define APR_MAX_IOVEC_SIZE 1024                /**< System dependent maximum 
  140.                                                     size of an iovec array */
  141. #elif defined(IOV_MAX)
  142. #define APR_MAX_IOVEC_SIZE IOV_MAX
  143. #elif defined(MAX_IOVEC)
  144. #define APR_MAX_IOVEC_SIZE MAX_IOVEC
  145. #else
  146. #define APR_MAX_IOVEC_SIZE 1024
  147. #endif
  148. /** @} */
  149.  
  150. /** File attributes */
  151. typedef apr_uint32_t apr_fileattrs_t;
  152.  
  153. /** Type to pass as whence argument to apr_file_seek. */
  154. typedef int       apr_seek_where_t;
  155.  
  156. /**
  157.  * Structure for referencing files.
  158.  */
  159. typedef struct apr_file_t         apr_file_t;
  160.  
  161. /* File lock types/flags */
  162. /**
  163.  * @defgroup apr_file_lock_types File Lock Types
  164.  * @{
  165.  */
  166.  
  167. #define APR_FLOCK_SHARED        1       /**< Shared lock. More than one process
  168.                                            or thread can hold a shared lock
  169.                                            at any given time. Essentially,
  170.                                            this is a "read lock", preventing
  171.                                            writers from establishing an
  172.                                            exclusive lock. */
  173. #define APR_FLOCK_EXCLUSIVE     2       /**< Exclusive lock. Only one process
  174.                                            may hold an exclusive lock at any
  175.                                            given time. This is analogous to
  176.                                            a "write lock". */
  177.  
  178. #define APR_FLOCK_TYPEMASK      0x000F  /**< mask to extract lock type */
  179. #define APR_FLOCK_NONBLOCK      0x0010  /**< do not block while acquiring the
  180.                                            file lock */
  181. /** @} */
  182.  
  183. /**
  184.  * Open the specified file.
  185.  * @param newf The opened file descriptor.
  186.  * @param fname The full path to the file (using / on all systems)
  187.  * @param flag Or'ed value of:
  188.  * <PRE>
  189.  *         APR_READ              open for reading
  190.  *         APR_WRITE             open for writing
  191.  *         APR_CREATE            create the file if not there
  192.  *         APR_APPEND            file ptr is set to end prior to all writes
  193.  *         APR_TRUNCATE          set length to zero if file exists
  194.  *         APR_BINARY            not a text file (This flag is ignored on 
  195.  *                               UNIX because it has no meaning)
  196.  *         APR_BUFFERED          buffer the data.  Default is non-buffered
  197.  *         APR_EXCL              return error if APR_CREATE and file exists
  198.  *         APR_DELONCLOSE        delete the file after closing.
  199.  *         APR_XTHREAD           Platform dependent tag to open the file
  200.  *                               for use across multiple threads
  201.  *         APR_SHARELOCK         Platform dependent support for higher
  202.  *                               level locked read/write access to support
  203.  *                               writes across process/machines
  204.  *         APR_FILE_NOCLEANUP    Do not register a cleanup with the pool 
  205.  *                               passed in on the <EM>pool</EM> argument (see below).
  206.  *                               The apr_os_file_t handle in apr_file_t will not
  207.  *                               be closed when the pool is destroyed.
  208.  *         APR_SENDFILE_ENABLED  Open with appropriate platform semantics
  209.  *                               for sendfile operations.  Advisory only,
  210.  *                               apr_socket_sendfile does not check this flag.
  211.  * </PRE>
  212.  * @param perm Access permissions for file.
  213.  * @param pool The pool to use.
  214.  * @remark If perm is APR_OS_DEFAULT and the file is being created,
  215.  * appropriate default permissions will be used.
  216.  */
  217. APR_DECLARE(apr_status_t) apr_file_open(apr_file_t **newf, const char *fname,
  218.                                         apr_int32_t flag, apr_fileperms_t perm,
  219.                                         apr_pool_t *pool);
  220.  
  221. /**
  222.  * Close the specified file.
  223.  * @param file The file descriptor to close.
  224.  */
  225. APR_DECLARE(apr_status_t) apr_file_close(apr_file_t *file);
  226.  
  227. /**
  228.  * Delete the specified file.
  229.  * @param path The full path to the file (using / on all systems)
  230.  * @param pool The pool to use.
  231.  * @remark If the file is open, it won't be removed until all
  232.  * instances are closed.
  233.  */
  234. APR_DECLARE(apr_status_t) apr_file_remove(const char *path, apr_pool_t *pool);
  235.  
  236. /**
  237.  * Rename the specified file.
  238.  * @param from_path The full path to the original file (using / on all systems)
  239.  * @param to_path The full path to the new file (using / on all systems)
  240.  * @param pool The pool to use.
  241.  * @warning If a file exists at the new location, then it will be
  242.  * overwritten.  Moving files or directories across devices may not be
  243.  * possible.
  244.  */
  245. APR_DECLARE(apr_status_t) apr_file_rename(const char *from_path, 
  246.                                           const char *to_path,
  247.                                           apr_pool_t *pool);
  248.  
  249. /**
  250.  * Copy the specified file to another file.
  251.  * @param from_path The full path to the original file (using / on all systems)
  252.  * @param to_path The full path to the new file (using / on all systems)
  253.  * @param perms Access permissions for the new file if it is created.
  254.  *     In place of the usual or'd combination of file permissions, the
  255.  *     value APR_FILE_SOURCE_PERMS may be given, in which case the source
  256.  *     file's permissions are copied.
  257.  * @param pool The pool to use.
  258.  * @remark The new file does not need to exist, it will be created if required.
  259.  * @warning If the new file already exists, its contents will be overwritten.
  260.  */
  261. APR_DECLARE(apr_status_t) apr_file_copy(const char *from_path, 
  262.                                         const char *to_path,
  263.                                         apr_fileperms_t perms,
  264.                                         apr_pool_t *pool);
  265.  
  266. /**
  267.  * Append the specified file to another file.
  268.  * @param from_path The full path to the source file (use / on all systems)
  269.  * @param to_path The full path to the destination file (use / on all systems)
  270.  * @param perms Access permissions for the destination file if it is created.
  271.  *     In place of the usual or'd combination of file permissions, the
  272.  *     value APR_FILE_SOURCE_PERMS may be given, in which case the source
  273.  *     file's permissions are copied.
  274.  * @param pool The pool to use.
  275.  * @remark The new file does not need to exist, it will be created if required.
  276.  */
  277. APR_DECLARE(apr_status_t) apr_file_append(const char *from_path, 
  278.                                           const char *to_path,
  279.                                           apr_fileperms_t perms,
  280.                                           apr_pool_t *pool);
  281.  
  282. /**
  283.  * Are we at the end of the file
  284.  * @param fptr The apr file we are testing.
  285.  * @remark Returns APR_EOF if we are at the end of file, APR_SUCCESS otherwise.
  286.  */
  287. APR_DECLARE(apr_status_t) apr_file_eof(apr_file_t *fptr);
  288.  
  289. /**
  290.  * Open standard error as an apr file pointer.
  291.  * @param thefile The apr file to use as stderr.
  292.  * @param pool The pool to allocate the file out of.
  293.  * 
  294.  * @remark The only reason that the apr_file_open_std* functions exist
  295.  * is that you may not always have a stderr/out/in on Windows.  This
  296.  * is generally a problem with newer versions of Windows and services.
  297.  * 
  298.  * @remark The other problem is that the C library functions generally work
  299.  * differently on Windows and Unix.  So, by using apr_file_open_std*
  300.  * functions, you can get a handle to an APR struct that works with
  301.  * the APR functions which are supposed to work identically on all
  302.  * platforms.
  303.  */
  304. APR_DECLARE(apr_status_t) apr_file_open_stderr(apr_file_t **thefile,
  305.                                                apr_pool_t *pool);
  306.  
  307. /**
  308.  * open standard output as an apr file pointer.
  309.  * @param thefile The apr file to use as stdout.
  310.  * @param pool The pool to allocate the file out of.
  311.  * 
  312.  * @remark See remarks for apr_file_open_stdout.
  313.  */
  314. APR_DECLARE(apr_status_t) apr_file_open_stdout(apr_file_t **thefile,
  315.                                                apr_pool_t *pool);
  316.  
  317. /**
  318.  * open standard input as an apr file pointer.
  319.  * @param thefile The apr file to use as stdin.
  320.  * @param pool The pool to allocate the file out of.
  321.  * 
  322.  * @remark See remarks for apr_file_open_stdout.
  323.  */
  324. APR_DECLARE(apr_status_t) apr_file_open_stdin(apr_file_t **thefile,
  325.                                               apr_pool_t *pool);
  326.  
  327. /**
  328.  * Read data from the specified file.
  329.  * @param thefile The file descriptor to read from.
  330.  * @param buf The buffer to store the data to.
  331.  * @param nbytes On entry, the number of bytes to read; on exit, the number
  332.  * of bytes read.
  333.  *
  334.  * @remark apr_file_read will read up to the specified number of
  335.  * bytes, but never more.  If there isn't enough data to fill that
  336.  * number of bytes, all of the available data is read.  The third
  337.  * argument is modified to reflect the number of bytes read.  If a
  338.  * char was put back into the stream via ungetc, it will be the first
  339.  * character returned.
  340.  *
  341.  * @remark It is not possible for both bytes to be read and an APR_EOF
  342.  * or other error to be returned.  APR_EINTR is never returned.
  343.  */
  344. APR_DECLARE(apr_status_t) apr_file_read(apr_file_t *thefile, void *buf,
  345.                                         apr_size_t *nbytes);
  346.  
  347. /**
  348.  * Write data to the specified file.
  349.  * @param thefile The file descriptor to write to.
  350.  * @param buf The buffer which contains the data.
  351.  * @param nbytes On entry, the number of bytes to write; on exit, the number 
  352.  *               of bytes written.
  353.  *
  354.  * @remark apr_file_write will write up to the specified number of
  355.  * bytes, but never more.  If the OS cannot write that many bytes, it
  356.  * will write as many as it can.  The third argument is modified to
  357.  * reflect the * number of bytes written.
  358.  *
  359.  * @remark It is possible for both bytes to be written and an error to
  360.  * be returned.  APR_EINTR is never returned.
  361.  */
  362. APR_DECLARE(apr_status_t) apr_file_write(apr_file_t *thefile, const void *buf,
  363.                                          apr_size_t *nbytes);
  364.  
  365. /**
  366.  * Write data from iovec array to the specified file.
  367.  * @param thefile The file descriptor to write to.
  368.  * @param vec The array from which to get the data to write to the file.
  369.  * @param nvec The number of elements in the struct iovec array. This must 
  370.  *             be smaller than APR_MAX_IOVEC_SIZE.  If it isn't, the function 
  371.  *             will fail with APR_EINVAL.
  372.  * @param nbytes The number of bytes written.
  373.  *
  374.  * @remark It is possible for both bytes to be written and an error to
  375.  * be returned.  APR_EINTR is never returned.
  376.  *
  377.  * @remark apr_file_writev is available even if the underlying
  378.  * operating system doesn't provide writev().
  379.  */
  380. APR_DECLARE(apr_status_t) apr_file_writev(apr_file_t *thefile,
  381.                                           const struct iovec *vec,
  382.                                           apr_size_t nvec, apr_size_t *nbytes);
  383.  
  384. /**
  385.  * Read data from the specified file, ensuring that the buffer is filled
  386.  * before returning.
  387.  * @param thefile The file descriptor to read from.
  388.  * @param buf The buffer to store the data to.
  389.  * @param nbytes The number of bytes to read.
  390.  * @param bytes_read If non-NULL, this will contain the number of bytes read.
  391.  *
  392.  * @remark apr_file_read will read up to the specified number of
  393.  * bytes, but never more.  If there isn't enough data to fill that
  394.  * number of bytes, then the process/thread will block until it is
  395.  * available or EOF is reached.  If a char was put back into the
  396.  * stream via ungetc, it will be the first character returned.
  397.  *
  398.  * @remark It is possible for both bytes to be read and an error to be
  399.  * returned.  And if *bytes_read is less than nbytes, an accompanying
  400.  * error is _always_ returned.
  401.  *
  402.  * @remark APR_EINTR is never returned.
  403.  */
  404. APR_DECLARE(apr_status_t) apr_file_read_full(apr_file_t *thefile, void *buf,
  405.                                              apr_size_t nbytes,
  406.                                              apr_size_t *bytes_read);
  407.  
  408. /**
  409.  * Write data to the specified file, ensuring that all of the data is
  410.  * written before returning.
  411.  * @param thefile The file descriptor to write to.
  412.  * @param buf The buffer which contains the data.
  413.  * @param nbytes The number of bytes to write.
  414.  * @param bytes_written If non-NULL, set to the number of bytes written.
  415.  * 
  416.  * @remark apr_file_write will write up to the specified number of
  417.  * bytes, but never more.  If the OS cannot write that many bytes, the
  418.  * process/thread will block until they can be written. Exceptional
  419.  * error such as "out of space" or "pipe closed" will terminate with
  420.  * an error.
  421.  *
  422.  * @remark It is possible for both bytes to be written and an error to
  423.  * be returned.  And if *bytes_written is less than nbytes, an
  424.  * accompanying error is _always_ returned.
  425.  *
  426.  * @remark APR_EINTR is never returned.
  427.  */
  428. APR_DECLARE(apr_status_t) apr_file_write_full(apr_file_t *thefile, 
  429.                                               const void *buf,
  430.                                               apr_size_t nbytes, 
  431.                                               apr_size_t *bytes_written);
  432.  
  433.  
  434. /**
  435.  * Write data from iovec array to the specified file, ensuring that all of the
  436.  * data is written before returning.
  437.  * @param thefile The file descriptor to write to.
  438.  * @param vec The array from which to get the data to write to the file.
  439.  * @param nvec The number of elements in the struct iovec array. This must 
  440.  *             be smaller than APR_MAX_IOVEC_SIZE.  If it isn't, the function 
  441.  *             will fail with APR_EINVAL.
  442.  * @param nbytes The number of bytes written.
  443.  *
  444.  * @remark apr_file_writev_full is available even if the underlying
  445.  * operating system doesn't provide writev().
  446.  */
  447. APR_DECLARE(apr_status_t) apr_file_writev_full(apr_file_t *thefile,
  448.                                                const struct iovec *vec,
  449.                                                apr_size_t nvec,
  450.                                                apr_size_t *nbytes);
  451. /**
  452.  * Write a character into the specified file.
  453.  * @param ch The character to write.
  454.  * @param thefile The file descriptor to write to
  455.  */
  456. APR_DECLARE(apr_status_t) apr_file_putc(char ch, apr_file_t *thefile);
  457.  
  458. /**
  459.  * Read a character from the specified file.
  460.  * @param ch The character to read into
  461.  * @param thefile The file descriptor to read from
  462.  */
  463. APR_DECLARE(apr_status_t) apr_file_getc(char *ch, apr_file_t *thefile);
  464.  
  465. /**
  466.  * Put a character back onto a specified stream.
  467.  * @param ch The character to write.
  468.  * @param thefile The file descriptor to write to
  469.  */
  470. APR_DECLARE(apr_status_t) apr_file_ungetc(char ch, apr_file_t *thefile);
  471.  
  472. /**
  473.  * Read a string from the specified file.
  474.  * @param str The buffer to store the string in. 
  475.  * @param len The length of the string
  476.  * @param thefile The file descriptor to read from
  477.  * @remark The buffer will be NUL-terminated if any characters are stored.
  478.  */
  479. APR_DECLARE(apr_status_t) apr_file_gets(char *str, int len, 
  480.                                         apr_file_t *thefile);
  481.  
  482. /**
  483.  * Write the string into the specified file.
  484.  * @param str The string to write. 
  485.  * @param thefile The file descriptor to write to
  486.  */
  487. APR_DECLARE(apr_status_t) apr_file_puts(const char *str, apr_file_t *thefile);
  488.  
  489. /**
  490.  * Flush the file's buffer.
  491.  * @param thefile The file descriptor to flush
  492.  */
  493. APR_DECLARE(apr_status_t) apr_file_flush(apr_file_t *thefile);
  494.  
  495. /**
  496.  * Duplicate the specified file descriptor.
  497.  * @param new_file The structure to duplicate into. 
  498.  * @param old_file The file to duplicate.
  499.  * @param p The pool to use for the new file.
  500.  * @remark *new_file must point to a valid apr_file_t, or point to NULL.
  501.  */         
  502. APR_DECLARE(apr_status_t) apr_file_dup(apr_file_t **new_file,
  503.                                        apr_file_t *old_file,
  504.                                        apr_pool_t *p);
  505.  
  506. /**
  507.  * Duplicate the specified file descriptor and close the original
  508.  * @param new_file The old file that is to be closed and reused
  509.  * @param old_file The file to duplicate
  510.  * @param p        The pool to use for the new file
  511.  *
  512.  * @remark new_file MUST point at a valid apr_file_t. It cannot be NULL.
  513.  */
  514. APR_DECLARE(apr_status_t) apr_file_dup2(apr_file_t *new_file,
  515.                                         apr_file_t *old_file,
  516.                                         apr_pool_t *p);
  517.  
  518. /**
  519.  * Move the specified file descriptor to a new pool
  520.  * @param new_file Pointer in which to return the new apr_file_t
  521.  * @param old_file The file to move
  522.  * @param p        The pool to which the descriptor is to be moved
  523.  * @remark Unlike apr_file_dup2(), this function doesn't do an
  524.  *         OS dup() operation on the underlying descriptor; it just
  525.  *         moves the descriptor's apr_file_t wrapper to a new pool.
  526.  * @remark The new pool need not be an ancestor of old_file's pool.
  527.  * @remark After calling this function, old_file may not be used
  528.  */
  529. APR_DECLARE(apr_status_t) apr_file_setaside(apr_file_t **new_file,
  530.                                             apr_file_t *old_file,
  531.                                             apr_pool_t *p);
  532.  
  533. /**
  534.  * Move the read/write file offset to a specified byte within a file.
  535.  * @param thefile The file descriptor
  536.  * @param where How to move the pointer, one of:
  537.  * <PRE>
  538.  *            APR_SET  --  set the offset to offset
  539.  *            APR_CUR  --  add the offset to the current position 
  540.  *            APR_END  --  add the offset to the current file size 
  541.  * </PRE>
  542.  * @param offset The offset to move the pointer to.
  543.  * @remark The third argument is modified to be the offset the pointer
  544.           was actually moved to.
  545.  */
  546. APR_DECLARE(apr_status_t) apr_file_seek(apr_file_t *thefile, 
  547.                                    apr_seek_where_t where,
  548.                                    apr_off_t *offset);
  549.  
  550. /**
  551.  * Create an anonymous pipe.
  552.  * @param in The file descriptor to use as input to the pipe.
  553.  * @param out The file descriptor to use as output from the pipe.
  554.  * @param pool The pool to operate on.
  555.  */
  556. APR_DECLARE(apr_status_t) apr_file_pipe_create(apr_file_t **in, 
  557.                                                apr_file_t **out,
  558.                                                apr_pool_t *pool);
  559.  
  560. /**
  561.  * Create a named pipe.
  562.  * @param filename The filename of the named pipe
  563.  * @param perm The permissions for the newly created pipe.
  564.  * @param pool The pool to operate on.
  565.  */
  566. APR_DECLARE(apr_status_t) apr_file_namedpipe_create(const char *filename, 
  567.                                                     apr_fileperms_t perm, 
  568.                                                     apr_pool_t *pool);
  569.  
  570. /**
  571.  * Get the timeout value for a pipe or manipulate the blocking state.
  572.  * @param thepipe The pipe we are getting a timeout for.
  573.  * @param timeout The current timeout value in microseconds. 
  574.  */
  575. APR_DECLARE(apr_status_t) apr_file_pipe_timeout_get(apr_file_t *thepipe, 
  576.                                                apr_interval_time_t *timeout);
  577.  
  578. /**
  579.  * Set the timeout value for a pipe or manipulate the blocking state.
  580.  * @param thepipe The pipe we are setting a timeout on.
  581.  * @param timeout The timeout value in microseconds.  Values < 0 mean wait 
  582.  *        forever, 0 means do not wait at all.
  583.  */
  584. APR_DECLARE(apr_status_t) apr_file_pipe_timeout_set(apr_file_t *thepipe, 
  585.                                                   apr_interval_time_t timeout);
  586.  
  587. /** file (un)locking functions. */
  588.  
  589. /**
  590.  * Establish a lock on the specified, open file. The lock may be advisory
  591.  * or mandatory, at the discretion of the platform. The lock applies to
  592.  * the file as a whole, rather than a specific range. Locks are established
  593.  * on a per-thread/process basis; a second lock by the same thread will not
  594.  * block.
  595.  * @param thefile The file to lock.
  596.  * @param type The type of lock to establish on the file.
  597.  */
  598. APR_DECLARE(apr_status_t) apr_file_lock(apr_file_t *thefile, int type);
  599.  
  600. /**
  601.  * Remove any outstanding locks on the file.
  602.  * @param thefile The file to unlock.
  603.  */
  604. APR_DECLARE(apr_status_t) apr_file_unlock(apr_file_t *thefile);
  605.  
  606. /**accessor and general file_io functions. */
  607.  
  608. /**
  609.  * return the file name of the current file.
  610.  * @param new_path The path of the file.  
  611.  * @param thefile The currently open file.
  612.  */                     
  613. APR_DECLARE(apr_status_t) apr_file_name_get(const char **new_path, 
  614.                                             apr_file_t *thefile);
  615.     
  616. /**
  617.  * Return the data associated with the current file.
  618.  * @param data The user data associated with the file.  
  619.  * @param key The key to use for retreiving data associated with this file.
  620.  * @param file The currently open file.
  621.  */                     
  622. APR_DECLARE(apr_status_t) apr_file_data_get(void **data, const char *key, 
  623.                                             apr_file_t *file);
  624.  
  625. /**
  626.  * Set the data associated with the current file.
  627.  * @param file The currently open file.
  628.  * @param data The user data to associate with the file.  
  629.  * @param key The key to use for assocaiteing data with the file.
  630.  * @param cleanup The cleanup routine to use when the file is destroyed.
  631.  */                     
  632. APR_DECLARE(apr_status_t) apr_file_data_set(apr_file_t *file, void *data,
  633.                                             const char *key,
  634.                                             apr_status_t (*cleanup)(void *));
  635.  
  636. /**
  637.  * Write a string to a file using a printf format.
  638.  * @param fptr The file to write to.
  639.  * @param format The format string
  640.  * @param ... The values to substitute in the format string
  641.  * @return The number of bytes written
  642.  */ 
  643. APR_DECLARE_NONSTD(int) apr_file_printf(apr_file_t *fptr, 
  644.                                         const char *format, ...)
  645.         __attribute__((format(printf,2,3)));
  646.  
  647. /**
  648.  * set the specified file's permission bits.
  649.  * @param fname The file (name) to apply the permissions to.
  650.  * @param perms The permission bits to apply to the file.
  651.  *
  652.  * @warning Some platforms may not be able to apply all of the
  653.  * available permission bits; APR_INCOMPLETE will be returned if some
  654.  * permissions are specified which could not be set.
  655.  *
  656.  * @warning Platforms which do not implement this feature will return
  657.  * APR_ENOTIMPL.
  658.  */
  659. APR_DECLARE(apr_status_t) apr_file_perms_set(const char *fname,
  660.                                              apr_fileperms_t perms);
  661.  
  662. /**
  663.  * Set attributes of the specified file.
  664.  * @param fname The full path to the file (using / on all systems)
  665.  * @param attributes Or'd combination of
  666.  * <PRE>
  667.  *            APR_FILE_ATTR_READONLY   - make the file readonly
  668.  *            APR_FILE_ATTR_EXECUTABLE - make the file executable
  669.  *            APR_FILE_ATTR_HIDDEN     - make the file hidden
  670.  * </PRE>
  671.  * @param attr_mask Mask of valid bits in attributes.
  672.  * @param pool the pool to use.
  673.  * @remark This function should be used in preference to explict manipulation
  674.  *      of the file permissions, because the operations to provide these
  675.  *      attributes are platform specific and may involve more than simply
  676.  *      setting permission bits.
  677.  * @warning Platforms which do not implement this feature will return
  678.  *      APR_ENOTIMPL.
  679.  */
  680. APR_DECLARE(apr_status_t) apr_file_attrs_set(const char *fname,
  681.                                              apr_fileattrs_t attributes,
  682.                                              apr_fileattrs_t attr_mask,
  683.                                              apr_pool_t *pool);
  684.  
  685. /**
  686.  * Set the mtime of the specified file.
  687.  * @param fname The full path to the file (using / on all systems)
  688.  * @param mtime The mtime to apply to the file.
  689.  * @param pool The pool to use.
  690.  * @warning Platforms which do not implement this feature will return
  691.  *      APR_ENOTIMPL.
  692.  */
  693. APR_DECLARE(apr_status_t) apr_file_mtime_set(const char *fname,
  694.                                              apr_time_t mtime,
  695.                                              apr_pool_t *pool);
  696.  
  697. /**
  698.  * Create a new directory on the file system.
  699.  * @param path the path for the directory to be created. (use / on all systems)
  700.  * @param perm Permissions for the new direcoty.
  701.  * @param pool the pool to use.
  702.  */                        
  703. APR_DECLARE(apr_status_t) apr_dir_make(const char *path, apr_fileperms_t perm, 
  704.                                        apr_pool_t *pool);
  705.  
  706. /** Creates a new directory on the file system, but behaves like
  707.  * 'mkdir -p'. Creates intermediate directories as required. No error
  708.  * will be reported if PATH already exists.
  709.  * @param path the path for the directory to be created. (use / on all systems)
  710.  * @param perm Permissions for the new direcoty.
  711.  * @param pool the pool to use.
  712.  */
  713. APR_DECLARE(apr_status_t) apr_dir_make_recursive(const char *path,
  714.                                                  apr_fileperms_t perm,
  715.                                                  apr_pool_t *pool);
  716.  
  717. /**
  718.  * Remove directory from the file system.
  719.  * @param path the path for the directory to be removed. (use / on all systems)
  720.  * @param pool the pool to use.
  721.  */                        
  722. APR_DECLARE(apr_status_t) apr_dir_remove(const char *path, apr_pool_t *pool);
  723.  
  724. /**
  725.  * get the specified file's stats.
  726.  * @param finfo Where to store the information about the file.
  727.  * @param wanted The desired apr_finfo_t fields, as a bit flag of APR_FINFO_ values 
  728.  * @param thefile The file to get information about.
  729.  */ 
  730. APR_DECLARE(apr_status_t) apr_file_info_get(apr_finfo_t *finfo, 
  731.                                             apr_int32_t wanted,
  732.                                             apr_file_t *thefile);
  733.     
  734.  
  735. /**
  736.  * Truncate the file's length to the specified offset
  737.  * @param fp The file to truncate
  738.  * @param offset The offset to truncate to.
  739.  */
  740. APR_DECLARE(apr_status_t) apr_file_trunc(apr_file_t *fp, apr_off_t offset);
  741.  
  742. /**
  743.  * Retrieve the flags that were passed into apr_file_open()
  744.  * when the file was opened.
  745.  * @return apr_int32_t the flags
  746.  */
  747. APR_DECLARE(apr_int32_t) apr_file_flags_get(apr_file_t *f);
  748.  
  749. /**
  750.  * Get the pool used by the file.
  751.  */
  752. APR_POOL_DECLARE_ACCESSOR(file);
  753.  
  754. /**
  755.  * Set a file to be inherited by child processes.
  756.  *
  757.  */
  758. APR_DECLARE_INHERIT_SET(file);
  759.  
  760. /**
  761.  * Unset a file from being inherited by child processes.
  762.  */
  763. APR_DECLARE_INHERIT_UNSET(file);
  764.  
  765. /**
  766.  * Open a temporary file
  767.  * @param fp The apr file to use as a temporary file.
  768.  * @param templ The template to use when creating a temp file.
  769.  * @param flags The flags to open the file with. If this is zero,
  770.  *              the file is opened with 
  771.  *              APR_CREATE | APR_READ | APR_WRITE | APR_EXCL | APR_DELONCLOSE
  772.  * @param p The pool to allocate the file out of.
  773.  * @remark   
  774.  * This function  generates  a unique temporary file name from template.  
  775.  * The last six characters of template must be XXXXXX and these are replaced 
  776.  * with a string that makes the filename unique. Since it will  be  modified,
  777.  * template must not be a string constant, but should be declared as a character
  778.  * array.  
  779.  *
  780.  */
  781. APR_DECLARE(apr_status_t) apr_file_mktemp(apr_file_t **fp, char *templ,
  782.                                           apr_int32_t flags, apr_pool_t *p);
  783.  
  784.  
  785. /**
  786.  * Find an existing directory suitable as a temporary storage location.
  787.  * @param temp_dir The temp directory.
  788.  * @param p The pool to use for any necessary allocations.
  789.  * @remark   
  790.  * This function uses an algorithm to search for a directory that an
  791.  * an application can use for temporary storage.  Once such a
  792.  * directory is found, that location is cached by the library.  Thus,
  793.  * callers only pay the cost of this algorithm once if that one time
  794.  * is successful.
  795.  *
  796.  */
  797. APR_DECLARE(apr_status_t) apr_temp_dir_get(const char **temp_dir, 
  798.                                            apr_pool_t *p);
  799.  
  800. /** @} */
  801.  
  802. #ifdef __cplusplus
  803. }
  804. #endif
  805.  
  806. #endif  /* ! APR_FILE_IO_H */
  807.